<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
        <title>Getting Started</title>
        <meta name="viewport" content="width=device-width, initial-scale=1">        
        <meta name="description" content="Pistache is a C++ REST framework focussed on high performance and clear API. Pistache is a free software written by Mathieu Stefani and available on Github - https://github.com/oktal/pistache
">
        <link rel="canonical" 
        href="http://pistache.io/quickstart">
        
        <!-- Harmony styles -->
        <link rel="stylesheet" type="text/css" href="/assets/css/main.css">

        <!-- Modernizr js -->
        <script async src="/assets/js/modernizr.js"></script>    

        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.0/gh-fork-ribbon.min.css" />
        <!--[if lt IE 9]>
            <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.0/gh-fork-ribbon.ie.min.css" />
        <![endif]-->

        <!-- IE Fixes -->
        <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
        <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
        <!--[if lt IE 9]>
          <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
          <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
        <![endif]-->        
    </head>
    <body class="theme-base-01">
        <header class="main-header">
            <div class="wc-container">
                <img id="img-logo" src="/assets/images/logo.png" />
                <h1>
                     <a href="/">Pistache</a>
                </h1>
                <h2>An elegant C++ REST framework.</h2>
                <ul>
    
    
		
  	
		
  	
		
  	
		
            <li>
                
                  <a href="/">Pistache</a><span>/</span>
                
            </li>
	    
  	
		
            <li>
                
                  <a class="active" href="/quickstart" class="active">Getting Started</a><span>/</span>
                
            </li>
	    
  	
		
            <li>
                
                  <a href="/guide/">User's Guide</a><span>/</span>
                
            </li>
	    
  	

	
	<li>
		<a title="Pistache on Github" 
			href="https://github.com/oktal/pistache" target="_blank">
			Source code
		</a><span>/</span>
	</li>
	
</ul>
                
                <div style="text-align: center">
                    <iframe src="https://ghbtns.com/github-btn.html?user=oktal&repo=pistache&type=star&count=true&size=large" frameborder="0" scrolling="0" width="160px" height="30px"></iframe>
                    <iframe src="https://ghbtns.com/github-btn.html?user=oktal&repo=pistache&type=fork&count=true&size=large" frameborder="0" scrolling="0" width="158px" height="30px"></iframe>
                </div>
            </div>
        </header>
        <div class="page-content wc-container">
	
	<div class="post">
		<h1>Getting Started</h1>
		<p class="post-meta">
			
	    <span class="post-date">
    	 
	    </span>
		</p>		
		<div class="post">
			<ul id="markdown-toc">
  <li><a href="#requirements" id="markdown-toc-requirements">Requirements</a></li>
  <li><a href="#installing-pistache" id="markdown-toc-installing-pistache">Installing Pistache</a></li>
  <li><a href="#pkgconfig-pistache" id="markdown-toc-pkgconfig-pistache">Using Pistache with pkg-config</a></li>
  <li><a href="#building-pistache" id="markdown-toc-building-pistache">Building Pistache</a></li>
  <li><a href="#serving-requests" id="markdown-toc-serving-requests">Serving requests</a>    <ul>
      <li><a href="#include" id="markdown-toc-include">Include</a></li>
      <li><a href="#hello-world" id="markdown-toc-hello-world">Hello World</a></li>
      <li><a href="#final-touch" id="markdown-toc-final-touch">Final touch</a></li>
    </ul>
  </li>
</ul>

<p><code>Pistache</code> is a web framework written in Modern C++ that focuses on performance and provides an elegant
and asynchronous API.</p>

<figure class="highlight"><pre><code class="language-cpp" data-lang="cpp"><span class="cp">#include &quot;pistache/pistache.h&quot;</span></code></pre></figure>

<h1 id="requirements">Requirements</h1>

<p><a href="https://git-scm.com/">git</a> is needed to retrieve the sources. Compiling the sources will require
<a href="http://cmake.org">CMake</a> to generate Makefile and a recent version of <code>g++</code> (at least 4.7).</p>

<p>Also, <code>Pistache</code> does not support Windows yet.</p>

<h1 id="installing-pistache">Installing Pistache</h1>

A request for official Debian sponsorship of our package was submitted on 23 April, 2019. You can follow its progress <a href="https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=927839">here</a>. In the mean time you can try our Ubuntu packages.

<p>To use our Ubuntu PPA for <a href="https://launchpad.net/%7Ekip/+archive/ubuntu/pistache">stable</a> packages, run the following:</p>

<p><code>
$ sudo add-apt-repository ppa:kip/pistache<br />
$ sudo apt update<br />
$ sudo apt install libpistache-dev<br />
</code></p>

<p>To use our Ubuntu PPA for <a href="https://launchpad.net/%7Ekip/+archive/ubuntu/pistache-unstable">unstable</a> packages, run the following:</p>

<p><code>
$ sudo add-apt-repository ppa:kip/pistache-unstable<br />
$ sudo apt update<br />
$ sudo apt install libpistache-dev<br />
</code></p>

<h1 id="pkgconfig-pistache">Using with pkg-config</h1>

<p>If you would like to automatically have your project's build environment use the appropriate compiler and linker build flags necessary to use Pistache, <a href="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</a> can greatly simplify things. The `libpistache-dev` package includes a pkg-config manifest.</p>

<p>To use with the GNU Autotools, as an example, include the following snippet in your project's `configure.ac`:</p>

<p><code>

    # Pistache...<br />
    PKG_CHECK_MODULES(<br />
        [libpistache], [libpistache >= 0.0], [],<br />
        [AC_MSG_ERROR([libpistache >= 0.0 missing...])])<br />
    YOURPROJECT_CXXFLAGS="$YOURPROJECT_CXXFLAGS $libpistache_CFLAGS"<br />
    YOURPROJECT_LIBS="$YOURPROJECT_LIBS $libpistache_LIBS"<br />

</code></p>


<h1 id="building-pistache">Building Pistache</h1>

<p>To download the latest available source, clone the repository over github.</p>

<p><code>
git clone https://github.com/oktal/pistache.git
</code></p>

<p>Then, init the submodules:</p>

<p><code>
git submodule update --init
</code></p>

<p>Now, compile the sources:</p>

<figure class="highlight"><pre><code class="language-console" data-lang="console"><span class="go">cd pistache</span>
<span class="go">mkdir build</span>
<span class="go">cd build</span>
<span class="go">cmake -G &quot;Unix Makefiles&quot; -DCMAKE_BUILD_TYPE=Release ..</span>
<span class="go">make</span>
<span class="go">sudo make install</span></code></pre></figure>

<p>Optionally, you can also run the tests:</p>

<figure class="highlight"><pre><code class="language-console" data-lang="console"><span class="go">make test</span></code></pre></figure>

<p>Be patient, <code>async_test</code> can take some time before completing.</p>

<p>And that’s it, now you can start playing with your newly installed <code>Pistache</code> framework.</p>

<h1 id="serving-requests">Serving requests</h1>

<h2 id="include">Include</h2>

<p>First, let’s start by including the right header</p>

<figure class="highlight"><pre><code class="language-cpp" data-lang="cpp"><span class="cp">#include &quot;pistache/endpoint.h&quot;</span></code></pre></figure>

<h2 id="hello-world">Hello World</h2>

<p>Requests received by <code>Pistache</code> are handled with an <code>Http::Handler</code>.</p>

<p>Let’s start by defining a simple <code>HelloHandler</code>:</p>

<figure class="highlight"><pre><code class="language-cpp" data-lang="cpp"><span class="k">using</span> <span class="k">namespace</span> <span class="n">Net</span><span class="p">;</span>

<span class="k">class</span> <span class="nc">HelloHandler</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Http</span><span class="o">::</span><span class="n">Handler</span> <span class="p">{</span>
<span class="k">public</span><span class="o">:</span>

    <span class="n">HTTP_PROTOTYPE</span><span class="p">(</span><span class="n">HelloHandler</span><span class="p">)</span>

    <span class="kt">void</span> <span class="n">onRequest</span><span class="p">(</span><span class="k">const</span> <span class="n">Http</span><span class="o">::</span><span class="n">Request</span><span class="o">&amp;</span> <span class="n">request</span><span class="p">,</span> <span class="n">Http</span><span class="o">::</span><span class="n">ResponseWriter</span> <span class="n">response</span><span class="p">)</span> <span class="p">{</span>
         <span class="n">response</span><span class="p">.</span><span class="n">send</span><span class="p">(</span><span class="n">Http</span><span class="o">::</span><span class="n">Code</span><span class="o">::</span><span class="n">Ok</span><span class="p">,</span> <span class="s">&quot;Hello, World&quot;</span><span class="p">);</span>
    <span class="p">}</span>
<span class="p">};</span></code></pre></figure>

<p>Handlers must inherit the <code>Http::Handler</code> class and at least define the <code>onRequest</code> member function.
They must also define a <code>clone()</code> member function. Simple handlers can use the special <code>HTTP_PROTOTYPE</code>
macro, passing in the name of the class. The macro will take care of defining the <code>clone()</code> member function
for you.</p>

<h2 id="final-touch">Final touch</h2>

<p>After defining the handler, the server can now be started:</p>

<figure class="highlight"><pre><code class="language-cpp" data-lang="cpp"><span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
    <span class="n">Net</span><span class="o">::</span><span class="n">Address</span> <span class="n">addr</span><span class="p">(</span><span class="n">Net</span><span class="o">::</span><span class="n">Ipv4</span><span class="o">::</span><span class="n">any</span><span class="p">(),</span> <span class="n">Net</span><span class="o">::</span><span class="n">Port</span><span class="p">(</span><span class="mi">9080</span><span class="p">));</span>

    <span class="k">auto</span> <span class="n">opts</span> <span class="o">=</span> <span class="n">Http</span><span class="o">::</span><span class="n">Endpoint</span><span class="o">::</span><span class="n">options</span><span class="p">().</span><span class="n">threads</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
    <span class="n">Http</span><span class="o">::</span><span class="n">Endpoint</span> <span class="n">server</span><span class="p">(</span><span class="n">addr</span><span class="p">);</span>
    <span class="n">server</span><span class="p">.</span><span class="n">init</span><span class="p">(</span><span class="n">opts</span><span class="p">);</span>
    <span class="n">server</span><span class="p">.</span><span class="n">setHandler</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_shared</span><span class="o">&lt;</span><span class="n">HelloHandler</span><span class="o">&gt;</span><span class="p">());</span>
    <span class="n">server</span><span class="p">.</span><span class="n">serve</span><span class="p">();</span>
<span class="p">}</span></code></pre></figure>

<p>For simplicity, you can also use the special <code>listenAndServe</code> function that will automatically create an
endpoint and instantiate your handler:</p>

<figure class="highlight"><pre><code class="language-cpp" data-lang="cpp"><span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
    <span class="n">Http</span><span class="o">::</span><span class="n">listenAndServe</span><span class="o">&lt;</span><span class="n">HelloHandler</span><span class="o">&gt;</span><span class="p">(</span><span class="s">&quot;*:9080&quot;</span><span class="p">);</span>
<span class="p">}</span></code></pre></figure>

<p>Note that by default, <code>listenAndServe</code> will only use 1 thread. You can tweak that by passing an <code>Options</code> argument
to the function:</p>

<figure class="highlight"><pre><code class="language-cpp" data-lang="cpp">    <span class="n">Http</span><span class="o">::</span><span class="n">listenAndServe</span><span class="o">&lt;</span><span class="n">HelloHandler</span><span class="o">&gt;</span><span class="p">(</span><span class="s">&quot;*:9080&quot;</span><span class="p">,</span> <span class="n">opts</span><span class="p">);</span></code></pre></figure>

<p>And that’s it, now you can fire up your favorite curl request and observe the final result:</p>

<figure class="highlight"><pre><code class="language-console" data-lang="console"><span class="go">curl http://localhost:9080/</span>
<span class="go">Hello, World</span></code></pre></figure>

<p>Complete code for this example can be found on Github:
 <a href="https://github.com/oktal/pistache/blob/master/examples/hello_server.cc">examples/hello_server.cc</a></p>

		</div>
	</div>


	

	<div class="post-footer">
		<div class="column-1">
			
				<span><< Older</span>
			
		</div>
		<div class="column-2"><a href="http://pistache.io/ ">Home</a></div>
		<div class="column-3">
			
				<span>Newer >></span>
			
		</div>
	</div>
</div>
 

        <footer class="main-footer">
            <div class="wc-container">
                <div class="column one">
                    <h6>Few more links</h6>
<ul class="menu">
</ul>		
                    
                </div>
                <div class="column two">
                    <h6>Follow me</h6>

<ul class="social-media">


    

    
    <li>
        <a title="oktal on Github" 
            href="https://github.com/oktal" 
            class="github wc-img-replace" target="_blank">Github</a>
    </li>
     

    

    

    

    

</ul>
                </div>
            </div>
            <p class="wc-container disclaimer">
                
Powered by <a href="http://jekyllrb.com" target="_blank">Jekyll</a>
            </p>
        </footer>
        <script type="text/javascript">
          /* To avoid render blocking css */
          var cb = function() {
            var l = document.createElement('link'); l.rel = 'stylesheet';
            l.href = 'http://fonts.googleapis.com/css?family=Ubuntu+Mono&subset=latin';
            var h = document.getElementsByTagName('head')[0]; h.parentNode.insertBefore(l, h);
          };
          var raf = requestAnimationFrame || mozRequestAnimationFrame ||
              webkitRequestAnimationFrame || msRequestAnimationFrame;
          if (raf) raf(cb);
          else window.addEventListener('load', cb);
        </script>
        <!-- jQuery -->
        <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
        <!-- When no internet load JQuery from local -->
        <script>window.jQuery || document.write('<script src="/assets/js/jquery.min.js"><\/script>')</script>
        <!-- Site js -->
        <script src="/assets/js/all.js"></script>
        <!-- Google analytics  -->
        
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-xxxx-x']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>

    </body>        
</html>
